Let’s read Julia documentation in your preferred language

SatoshiTerasaki@AtelierArith

Overview

  • Introduction to DocstringTranslation.jl
  • Multilingual translation of Julia documentation
  • Running demonstration

Background and Challenges

if you in Set(NativeEnglishSpeakers)
    println("No problem :D")
elseif you  Set(GoodAtReadingEnglish)
    println("It's O.K.")
else
    lang = native_language(you) # e.g., Japanese
    @assert lang  "English"
    println("Meh.")
    println("It takes a lot of time to understand correctly.")
    println("I want to read documentation in $(lang)")
end

Background and Challenges

  • All up-to-date information is provided only in English
    • It’s O.K. English is a common language
  • For non-English-speaking developers, reading and participating in discussions in English represents significant psychological and time costs
    • This is a yet another two-language problem
  • Manual translation processes require significant time

Challenges (in Japan)

  • The number of people who use English daily is limited. Many technical documents are expected to be readable in Japanese.
  • In Japan especially in industry, C++/Python is widely used in industry. There is lots of Japanese documentation (including blog post) for C++/Python.
    • “I don’t want to use Julia because it is a minor language” C++ user says
    • “Julia is difficult” C++ user says
    • “Few libraries and documentation available for Julia” Python user says
    • “Production systems must strictly prohibit the use of the Julia language. From now on, if you use it, be prepared for possible termination.” CEO at my workplace (This is NOT a joke.)

Challenges (in Japan)

  • Starting August 2025, I’ll be unemployed. This Is Not a Drill.
  • To grow the Julia community in Japan, I think we need documentation written in Japanese. That’s why I created DocstringTranslation.jl package.

Solution

What is DocstringTranslation.jl?

A package for translating Julia docstrings using OpenAI API

@doc exp (Original)

julia> @doc exp
  exp(x)

  Compute the natural base exponential of x, in other words ^x.

  See also exp2, exp10, and cis.

  Examples
  ≡≡≡≡≡≡≡≡

  julia> exp(1.0)
  2.718281828459045

  julia> exp(im * pi)  cis(pi)
  true

  exp(A::AbstractMatrix)

  Compute the matrix exponential of A, defined as:

  e^A = \sum_{n=0}^{\infty} \frac{A^n}{n!}.

  For symmetric or Hermitian matrices A, an eigendecomposition (eigen) is used; otherwise, the scaling and squaring algorithm
  (see [^H05]) is employed.

  │ [^H05]

  │  Nicholas J. Higham, "The squaring and scaling method for the matrix exponential revisited", SIAM Journal
  │  on Matrix Analysis and Applications, 26(4), 2005, 1179-1193. doi:10.1137/090768539
  │  (https://doi.org/10.1137/090768539)

  Examples
  ≡≡≡≡≡≡≡≡

  julia> A = Matrix(1.0I, 2, 2)
  2×2 Matrix{Float64}:
   1.0  0.0
   0.0  1.0

  julia> exp(A)
  2×2 Matrix{Float64}:
   2.71828  0.0
   0.0      2.71828

@doc exp (Translated into Japanese)

julia> ENV["OPENAI_API_KEY"] = "sk-<blah>"
julia> using DocstringTranslation
julia> @switchlang! :ja
julia> @doc exp
  exp(x)

  xの自然基底指数を計算します。言い換えれば、ℯ^xです。

  他にexp2、exp10、およびcisも参照してください。


  ≡≡

  julia> exp(1.0)
  2.718281828459045

  julia> exp(im * pi)  cis(pi)
  true

  exp(A::AbstractMatrix)

  行列 A の行列指数関数を計算します。定義は次の通りです。

  e^A = \sum_{n=0}^{\infty} \frac{A^n}{n!}.

  対称行列またはエルミート行列 A
  の場合は、固有分解(eigen)が使用され、それ以外の場合はスケーリングと平方化アルゴリズム([^\H05]を参照)が選択されます。

  │ [^H05]

  │  Nicholas J. Higham, "The squaring and scaling
  │  method for the matrix exponential revisited",
  │  SIAM Journal on Matrix Analysis and
  │  Applications, 26(4), 2005, 1179-1193.
  │  doi:10.1137/090768539
  │  (https://doi.org/10.1137/090768539)


  ≡≡

  julia> A = Matrix(1.0I, 2, 2)
  2×2 Matrix{Float64}:
   1.0  0.0
   0.0  1.0

  julia> exp(A)
  2×2 Matrix{Float64}:
   2.71828  0.0
   0.0      2.71828

What is DocstringTranslation.jl?

How Translation Works

  • @switchlang! :ja overrides the Docs.parsedoc(d::DocStr) method.
# Rough implementation outline
@eval function Docs.parsedoc(d::DocStr)
    if d.object === nothing
        md = Docs.formatdoc(d)
        md.meta[:module] = d.data[:module]
        md.meta[:path] = d.data[:path]
        begin # workaround
          translated_md = translate_docstring_with_openai(md)
        end # workaround
        d.object = translated_md
    end
    d.object
end

For more details, refer to the actual implementation.

Docstrings on IJulia.jl

We can view translated docstrings in Jupyter

Live Docs on Pluto.jl

We can view translated docstrings in Pluto

Translation of Documenter.jl-based documentation

--- a/docs/make.jl
+++ b/docs/make.jl
@@ -4,6 +4,10 @@ using DocumenterCitations
 # `using SpecialFunctions` for all doctests
 DocMeta.setdocmeta!(SpecialFunctions, :DocTestSetup, :(using SpecialFunctions); recursive=true)

+using DocstringTranslation
+@switchlang! :ja
+DocstringTranslation.switchtargetpackage!(SpecialFunctions)
+
 bib = CitationBibliography(
        joinpath(@__DIR__, "src", "refs.bi
b");
        style = :authoryear,

Translation of Documenter.jl-based documentation

Translation Results for Julia’s Official Documentation

Multilingual Julia Documentation:

About Result Caching

  • Uses Scratch.jl to store translation results locally
  • Prevents repeated API calls each time the REPL starts
  • Allows modification of translation results by editing <lang>.md files (e.g., ja.md)
  • Enables sharing of translation results among users
$ tree ~/.julia/scratchspaces/d404e13b-1f8e-41a5-a26a-0b758a0c6c97/translation
├── Base
│   └── 1.11
│       └── Math
│           └── 77be4ada26c623c913ebbdae5d8450a4dfe8f3cbf67837faac9d7193342d2bfe
│               ├── ja.md
│               └── original.md
└── LinearAlgebra
    └── 1.11
        └── 46c0494a8a2adffc6f71752b60448da1743997b5b1791b71e3830113e9b9cc46
            ├── ja.md
            └── original.md

8 directories, 4 files

Additional Information

  • DocstringTranslation.jl (OpenAI backend)
  • DocstringTranslationOllamaBackend.jl (Ollama backend)
  • DocstringTranslationPLaMoBackend.jl (PLaMo backend)

Demo

  • Let’s see the translation functionality in action!
  • Please come to me !!!

Summary

  • Enables multilingual support for Julia documentation
  • Supports both docstrings and Documenter.jl
  • Improves efficiency through result caching
  • Supports multiple translation backends

Future Plans:

  • Add support for more languages
  • Facilitate community sharing of translation results

Thank You

Repositories: